home *** CD-ROM | disk | FTP | other *** search
/ Disc to the Future 2 / Disc to the Future Part II Programmer's Reference (Wayzata Technology)(6013)(1992).bin / MAC / ASSEMBLE / MDSCVT.TXT < prev   
Text File  |  1990-08-25  |  6KB  |  191 lines
  1. Converting Assembly Language Files from MDS to MPW Format
  2. August 20, 1990
  3.  
  4.  
  5. Jon Bell
  6. Dept. of Physics & Computer Science
  7. Presbyterian College
  8. Clinton SC 29325
  9. (CIS #70441,353)
  10.  
  11.  
  12. (inspired by an article by Dan Weston,
  13. in the June 1989 issue of MacTutor magazine)
  14.  
  15.  
  16. Introduction
  17. ------------
  18.  
  19. Most Macintosh assembly-language programming now seems to be done with
  20. the Macintosh Programmer's Workshop (MPW) assembler from Apple.  Unfor-
  21. tunately, most books on Macintosh assembly language programming were 
  22. written for the MPW assembler's predecessor, the Macintosh Development
  23. System (MDS), originally sold by Apple but now distributed by Consulair.
  24.  
  25. This note describes the "bare minimum" changes which need to be made
  26. to a program to convert it from MDS to MPW format.  These should be 
  27. sufficient to convert the example programs in Dan Weston's "Complete Book 
  28. of Macintosh Assembly Language Programming."
  29.  
  30.  
  31. 1.  Declaring Procedures
  32. ------------------------
  33.  
  34. The basic unit of code in MPW is the "code module".  Your source program 
  35. must contain at least one code module.  A module begins with one of the
  36. following directives:
  37.  
  38.     MAIN        for a main program (must have exactly one)
  39.     PROC        for a procedure
  40.     FUNC        for a function
  41.  
  42. A module can end either with ENDMAIN, ENDPROC or ENDFUNC, or with the
  43. MAIN, PROC or FUNC which begins the next code module.
  44.  
  45. I usually put the program, procedure or function name in the MAIN, PROC
  46. or FUNC directive:
  47.  
  48. MyProgram    MAIN
  49.         ...
  50.         ENDMAIN
  51.  
  52.  
  53. 2.  Separating code and data
  54. ----------------------------
  55.  
  56. Assembly language programs use DS directives to declare global variables.
  57. In MDS, you can place the DS directives wherever you like in your program; 
  58. the linker collects all the globals together and allocates one block
  59. of memory for them.  In MPW you can do much the same thing.  However, it 
  60. makes a difference whether you put the DS directives inside or outside
  61. a code module.  If you put DS directives _inside_ a code module, you must
  62. set off each group of DS directives by placing a DATA directive before 
  63. it and a CODE directive after it:
  64.  
  65. MyProgram    MAIN
  66.         DATA
  67. var1        DS.B    1
  68. var2        DS.L    1
  69. ...        ...
  70.         CODE
  71. (instructions)
  72.         DATA
  73. (more variables)
  74.         CODE
  75. (more instructions)
  76.         ENDMAIN
  77.  
  78. If you put all your DS directives _outside_ the code module, either before it
  79. or after it, you don't have to worry about this.
  80.  
  81.  
  82. 3.  Declaring the QuickDraw globals
  83. -----------------------------------
  84.  
  85. Practically all MDS programs have the following "magic incantation" at
  86. the beginning of the initialization section:
  87.  
  88.     pea    -4(A5)
  89.     _InitGraf
  90.  
  91. The parameter to InitGraf is actually tells InitGraf where to put the
  92. block of global variables which QuickDraw uses.  In particular, the
  93. parameter is a pointer to the variable "thePort", which (after initialization)
  94. becomes a pointer to the current GrafPort.  "ThePort" is located at the top of 
  95. the block of QuickDraw globals, which is 106 bytes long.  The first byte of 
  96. "thePort" is the 103rd byte of the QD globals, because we count the bytes 
  97. upward from the bottom of the block.
  98.  
  99. The MDS linker, by default, reserves space for the QD globals 
  100. immediately below the address stored in register A5 (the "A5 boundary").
  101. It does this by allocating your own globals beginning 256 bytes below
  102. the A5 boundary.  Since the QD globals occupy only 106 bytes,
  103. this actually leaves some unused space between the QD globals and your
  104. own globals.
  105.  
  106. The MPW linker, on the other hand, does _not_ automatically allocate
  107. space for the QuickDraw globals, but simply begins allocating _your_
  108. globals immediately below the A5 boundary.  If you blindly use "pea -4(A5)" to
  109. set up InitGraf, the QuickDraw globals will end up occupying space which
  110. was reserved for _your_ globals.  When you put a value in the global
  111. variable which occupies the space where QuickDraw _thinks_ "thePort" is,
  112. QuickDraw will take that value as the address of the current GrafPort,
  113. and *** blammo! ***
  114.  
  115. Therefore, in MPW, _you_ must explicitly declare the QuickDraw globals 
  116. in your program, and pass InitGraf a pointer to "thePort".  The simplest
  117. way to do this is to declare
  118.  
  119. QDGlobals    DS.B    GrafSize
  120.  
  121. along with your other global variables, then replace the "magic incantation"
  122. with
  123.  
  124.     pea    QDGlobals+GrafSize-4(A5)
  125.     _InitGraf
  126.  
  127. The constant "GrafSize" is defined as 106 (the total size of the QD globals
  128. area) in the include file "QuickEqu.D".  The effective address therefore
  129. points 4 bytes into the QD globals, starting from the top, which is the
  130. location of "thePort".  Of course, you could also write this as
  131.  
  132.     pea    QDGlobals+102(A5)
  133.     _InitGraf
  134.  
  135. but I like to use the predefined constants wherever possible.
  136.  
  137. Note that you can do exactly the same thing in MDS.  In this case you
  138. can tell the linker to start your globals immediately below the A5
  139. boundary by including the command "/Globals 0" in your link control file.
  140.  
  141.  
  142. 4.  Changing Directives
  143. -----------------------
  144.  
  145. If your MDS program is divided into more than one source file, it probably
  146. uses XDEF and XREF directives to allow one file to use symbols defined
  147. in another one.  MPW uses the directives EXPORT and IMPORT in their place.
  148. Simply replace XDEF and XREF with EXPORT and IMPORT wherever they occur.
  149.  
  150. There may be other directives that need changing, but I haven't found any
  151. yet, at least not in Dan Weston's example programs.
  152.  
  153.  
  154. 5.  Labels
  155. ----------
  156.  
  157. In MDS, labels customarily begin in the first column of a line, but you
  158. can indent them if you follow them with a colon:
  159.  
  160. MyRecord    DS.L    0
  161.   Field1:    DS.L    1
  162.   Field2:    DS.L    1
  163.   Field3:    DS.W    1
  164.   
  165. This comes in handy sometimes for defining record-like structures.
  166.  
  167. In MPW, you cannot do this.  All labels _must_ start in the first column.
  168.  
  169.  
  170. 6.  Macros
  171. ----------
  172.  
  173. MPW macros have a different format from MDS macros:
  174.  
  175. MDS:    MACRO    _SFGetFile =
  176.     move.w    #2, -(SP)
  177.     _Pack3
  178.     |
  179.  
  180. MPW:    MACRO
  181.     _SFGetFile
  182.     move.w    #2, -(SP)
  183.     _Pack3
  184.     ENDM
  185.  
  186.  
  187. If you run into any problems with the above guidelines, or if you encounter
  188. any other things which need to be converted, please feel free to drop me a 
  189. line at the address above, or post me a message in MACDEV, or send me an e-mail.
  190.  
  191.